Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / wasm.arc / WASM.DOC < prev

Wrap

Text File | 1986-02-19 | 101.0 KB | 3,722 lines

\\\ WASM /// Version 1.0 Wolfware Assembler for the IBM Personal Computer (C) Copyright 1985 by Eric Tauck Wolfware (tm) A Short Description of WASM - WASM is an assembler. It takes a standard DOS ASCII text file of 8088 instruction mnemonics for input and produces an executable COM file and an optional list file for output. - Features: supports full range of 8088 instructions and most standard "pseudo operations" to fully control assembly, signed and unsigned numbers, operand expressions, produces executable code (does not require linking), BASIC subroutines, fast operation, and efficient use of memory. - Minimum system requirements: IBM PC or compatible, DOS 1.0 and up, and 64K memory. - This version of WASM does NOT support macros, external linking, or multisegment definitions. Foreword High level languages like BASIC and Pascal can make the creation of a working program a simple and straightforward process. There is a price to this convenience though, control and freedom. High level languages rarely take full advantage of a particular machine's potential. The only way to tap the full resources of a computer is to program in assembly language. Assembly language programming has immediate and practical benefits: - Programs can be made to run hundreds, maybe thousands of times faster than their high level language counterparts. - Programs can take full advantage of the capabilities of the machine it was meant to run on. - The actual code needed to run the program is usually much less then the code resulting from programs written in high level languages. If one is willing to sacrifice the ease of use and portability of high level languages, the results of assembly language programming can be quite rewarding. WASM Distribution Policy Unmodified copies of this program and documentation may be freely shared and distributed. Under no circumstances may this program be sold for profit without the express consent of the author. Use this program at your own risk. The author assumes no responsibility for damages real or imaginary resulting from this work. Send all questions, comments, and complaints to: Eric Tauck Wolfware 1304 Deerpass Rd. Marengo, IL 60152 Compuserve: 72457,1557 Table of Contents Introduction .................................. 1 Running WASM .................................. 2 Assembly Listing .............................. 4 Basic Syntax .................................. 8 Operands ..................................... 10 Special Operands ............................. 18 Combining Operands ........................... 21 Pseudo-Op Descriptions ....................... 22 WASM Instruction Set ......................... 29 Source Code Clarification .................... 39 Errors ....................................... 43 Programming .................................. 51 Reserved Symbols ............................. 56 Technical Notes .............................. 57 Introduction 1 WASM is designed for quick and easy assembly programming. It is best used for writing smaller or ad hoc programs, system patches, utilities, etc. WASM is comparable to other assemblers in terms of what it will and won't do. Some things that are NOT supported in this version of WASM are macros, external linking, and multisegment definitions. These three things are mostly time savers, and useful though they can be, there is little that can be done with them that can't be without them. The code produced by WASM is a memory image, COM file format. It is ready for execution and does not require processing by the linker. If you do not know anything or very little about assembly language programming on the 8088, you will probably need to acquire a book on the subject. Try to get one that does not stress a particular assembler, but one about programming on the 8088 microprocessor in general. Running WASM 2 Once you have a program to assemble, from DOS type WASM. WASM will display a short message and then prompt you for the name of the source file, object file, and list file. - If no extension is given for the source file, an extension of ASM will be added. - If you just press enter for the name of the object file, WASM will default to the name and drive of your source file with an extension of COM. - If you just press enter for the list file, WASM will not generate a list output (this will speed up assembly). If a name without an extension is entered, WASM will add an extension of LST. If no drive is specified, the object file drive will be used. Instead of entering the name of a file in which to save the listing, you may enter a device name. Entering CON will send the list output to the screen and entering PRN will send it to the printer (see the section in the DOS manual on reserved device names). The names of the files can be entered as parameters when WASM is initially executed. The first parameter is the source name, the second is the object name, and the third is the list name. The same rules for the names apply. If a parameter is left out then the default name will be used (though names can only be left off the end, for instance you can't give the list file name without the object and source file names). Examples: WASM TEST Will read from the source file TEST.ASM on the default drive, write the object file TEST.COM on the default drive, and not generate a listing. WASM A:TEST B: Will read from the source file TEST.ASM on drive A, write the object file TEST.COM to drive B, and not generate a listing. WASM A:TEST B: TEST Will read from the source file TEST.ASM on drive A, write the object file TEST.COM to drive B, and write the list file TEST.LST to drive B. WASM A:TEST B: A:TEST Will read from the source file TEST.ASM on drive A, write the object file TEST.COM to drive B, and write the list file TEST.LST to drive A. Running WASM 3 WASM A:TEST B: CON Will read from the source file TEST.ASM on drive A, write the object file TEST.COM to drive B, and display the listing on the screen. WASM B:CLP .BLD Will read from the source file CLP.ASM on drive B, write the object file CLP.BLD to drive B, and not generate a listing. BLD makes a good extension for BLOADable files. WASM A:TEST.TXT A:.BIN PRN Will read from the source file TEST.TXT on drive A, write the object file TEST.BIN to drive A, and send the listing to the printer. Note: WASM does not check to see if the printer is ready, so make sure the printer is properly set up before sending any list output there. Path names for DOS 2.0 and up are not recognized. All files must be in the current directory. Any errors detected in the source code will be displayed to the screen if a listing is not being generated. Assembly, depending on the size of the source file, should take anywhere from several seconds to several minutes (about 30 lines/second if the files are on floppy disk drives). When assembly is complete control is returned to DOS. The resulting object code is ready to be executed. Assembly Listing: Description 4 Initially and at the beginning of each page of list output WASM displays various assembly information. In the upper right corner is the WASM version and page number, just below is the assembly time and date, and finally below that is the name of the source file. In the upper left corner is the program title, and right below is the subtitle. The title and subtitle are optional and may be set by the user with the TITLE and SUBTITLE pseudo-ops. Following all this is a header for the listing. The header labels represent the following: LOC stands for location counter, OBJ stands for object code, LINE is the line number, and SOURCE is the source code. The actual listing is then displayed, lined up below the appropriate labels. The source line is truncated if necessary to make the length of the entire list line equal to the width setting (the default setting is 79). The width may be modified by the LINESIZE pseudo-op. Lines with no code, lines with only a comment, and certain pseudo-ops do not display the location counter. The EQU statement displays its value indented from the start of the location counter column. EQU statements that name memory locations put brackets around their value. Line which do not generate any object code do not (cannot) display any object code. The DS pseudo-op never displays its object code. PROC statements display the present PROC nest level in the object code column. Included source code (through the use of the INCLUDE pseudo-op) does its own line numbering based on the line number within the included file. When an included file ends, the line numbering picks up where it had left off. All included source code has a dash immediately following the line number. The INCLUDE line itself is always output whether or not a listing is being generated. This output allows the determination of which included file contained an error, useful when there are several included files and a listing is not being generated. If paging has been activated through the PAGE+ pseudo-op, a new page is started after every 60 list lines. Every new page after the first begins with a form feed (ASCII 12). The number of lines per page may be modified through the use of the PAGESIZE pseudo-op. At the end of assembly WASM displays the number of errors detected (including diagnostics), the total number of source lines processed, the number of bytes of code. Assembly Listing: Description 5 Finally, if a listing is being generated, the symbol table will be displayed in alphabetical order. The first ten characters and the hex value of each symbol is shown. Undefined symbols are included in the table with a value of ????. Underscores are ignored for purposes of alphabetization, i.e. something like "A_A" would be considered equal to "AA". Assembly Listing: Example 6 List Example WASM/1.0 -- Page 1 Size Checker Feb 14, 1986 at 04:26:22 Source file: CHECK.ASM LOC OBJ LINE SOURCE WOLFWARE ASSEMBLER 1 ;-------------------------------------; 2 ; List Example ; 3 ;Compare available memory to 500 and ; 4 ;print response. This is a program to ; 5 ;show an example of the assembly ; 6 ;listing. ; 7 ;-------------------------------------; 8 9 LINESIZE 68 10 TITLE 'List Example','Size Checker' 11 0100 -> 1 12 PROC FAR 13 01F4 14 PRO_BYTE EQU 500 ;needed [0006] 15 SEG_BYTE EQU WORD [0006H] ;available 16 17 ;----- check memory 18 0100 813E0600F401 19 CMP SEG_BYTE,PRO_BYTE ;check bytes 0106 7208 20 JB SIZERR ;jump if err 21 22 ;----- memory OK 23 0108 BA1B01 24 MOV DX,OFFSET MESS_OK ;OK mess 010B E80A00 25 CALL DISPLAY ;display 010E CD20 26 INT 20H ;exit to DOS 27 28 ;----- memory error 29 0110 30 SIZERR - - - Error: Undefined symbol: MESS_ER 0110 BA0000 31 MOV DX,OFFSET MESS_ER ;error mess 0113 E80200 32 CALL DISPLAY ;display 0116 CD20 33 INT 20H ;exit to DOS 34 Assembly Listing: Example 7 List Example WASM/1.0 -- Page 2 Data Feb 14, 1986 at 04:26:23 Source file: CHECK.ASM LOC OBJ LINE SOURCE WOLFWARE ASSEMBLER 35 PAGE 'Data' 36 37 ;----- external message display routine 38 0118 39 INCLUDE 'DISPLAY' ;incl file 0118 -> 2 1 - DISPLAY PROC NEAR - - - Error: Syntax error: MOB 0118 2 - MOB AH,9 ;print str 0118 CD21 3 - INT 21H ;DOS function 011A C3 4 - RET 011B -> 2 5 - ENDP 40 41 ;----- response messages 42 011B 546865726520 43 MESS_OK DB 'There is enough memory$' 697320656E6F 756768206D65 6D6F727924 0132 4E656564206D 44 MESS_ERR DB 'Need more memory$' 6F7265206D65 6D6F727924 45 0143 -> 1 46 ENDP 2 Error(s) detected 51 Line(s) processed 67 Byte(s) of code 7 Symbol(s) SYMBOL TABLE DUMP: DISPLAY 0118 MESS_ER ???? MESS_ERR 0132 MESS_OK 011B PRO_BYTE 01F4 SEG_BYTE 0006 SIZERR 0110 Basic Syntax 8 WASM accepts a standard DOS text file for input as source code. Lines may be up to 255 characters long. Upper and lower-case are not distinguished. All letters except those in strings are converted to upper-case. Spaces and all control characters are always treated as delimiters. Commas, +, -, *, -, [, ], are also treated as delimiters but have special meaning. Single quotes are used to delimit strings and semi- colons indicate comments. All other characters are assumed to be part of the fields representing the labels, instructions, and operands. An end of file marker (ASCII 26) is assumed to mark the end of the source file, even if there is more text in the file. If no end of file marker is found, WASM reads the number of bytes specified in the directory. Every line of source code is divided up into fields. The fields are always separated from each other by one or more delimiters. WASM determines the purpose of a field by the position it occupies in the source line. Each source line uses the following format: Label Instruction Operand(s) ;Comment Labels Labels may or may not be required, depending upon the instruction. Labels may stand alone (i.e. be the only thing in the line). Anything beginning in the first column is considered a label. A label may be separated by any number of spaces from the instruction. Labels may be any size and consist of any characters. All labels must be unique from each other and other operand types. It is recommended that labels begin with a letter A to Z and consist of only letters, numbers, and underscores. See also the Reserved Symbols section. Instructions Instructions are the next field after labels. If a source line does not contain a label then the first field is the instruction. An instruction can begin in any column but the first. At least one space must separate a label from an instruction on the same line. There can never be any operands without an instruction. The available instructions are described in the WASM Instruction Set and the Pseudo-Op Descriptions sections. Basic Syntax 9 Operands All the fields after the instruction are defined as operands. The actual number of operands required is determined by the instruction. WASM ignores extra operands after the required ones. There should be at least one space between an instruction and its operands. Commas and spaces are usually used to separate operands from each other. Commas act as "hard delimiters" by forcing the final evaluation of an operand. Without a comma WASM will evaluate the first expression (field) and then search for a plus, minus, or similar operator to use to combine the next expression with the first. The valid operand types are described in the Operands section. Comments Comments only serve to explain the source code and are always optional. Comments must appear at the end of the source line. Lines may contain only a comment. Comments never have any effect on the assembly itself. All source code on a single line following a semicolon is considered a comment and is disregarded. Note that semicolons are treated as comment indicators even within strings, and can only be represented as data by their numerical value. Operands: General 10 Operands can be described according to three different qualities: type, size, and value. The type describes where the bits that are being acted upon are coming from and where they are going (registers, immediate data, etc.); the size describes how many bits are being acted upon (8 bits, 16 bits, etc.); and the value describes which bits are one and which are zero (43, -8, 10, etc.). The following subsections formally describes operands in terms of these three qualities. In practice, the knowledge of the 8088 architecture makes much of this information is intuitive. Basically the type and size of the operands must match those of the instruction. For each version of each instruction the allowable types and sizes of the operands are given in the WASM Instruction Set section. Operands: Types 11 WASM figures out the type of an operand by looking at it and trying to match it to one of the formats it recognizes. The following is a summary of the legal operand types and their formats: I. Immediate data operands. A. Numbers with an optional plus or minus preceding it. All numbers must begin with a 0 to 9, and anything that begins as such is considered a number. Numbers with a sign must be in the range -32768 to +32767, otherwise they must be 0 to 65535 1. A binary number of up to 16 digits of ones and zeros followed by a "B". 2. A decimal number from 0 to 65535. 3. A hexadecimal number of up to 4 digits of 0 to F followed by an "H". Hexadecimal numbers that begin with A to F should have a preceding 0. B. A single character enclosed in single quotes (except a semicolon, see part V). The character is converted to an ASCII value, so 'z' would be the same as the number 122. C. A single question mark may be used to indicate that the value is not known or not important. WASM interprets a question mark as zero. II. Register operands. A. One of the following 8 bit registers: AH AL BH BL CH CL DH DL B. One of the following 16 bit registers: AX BX CX DX SP BP SI DI C. One of the following segment registers: CS SS DS ES III. Memory operands. A. Direct addressing. 1. A label that identifies a memory location or data (memory label). Operands: Types 12 2. A value enclosed by brackets. All numbers (immediate data) inside the brackets are added or subtracted together to form the value. B. Indirect addressing through the use of one of the following register combinations with an optional value added or subtracted in: BX BP DI SI BX+DI BX+SI BP+DI BP+SI The entire combination is surrounded by brackets. The registers can appear in any order and may be mixed up with any numbers. All numbers (immediate data) are added or subtracted together to form the value. The OFFSET special operand may be used, though it can be assumed for any labels. IV. A label that marks some location in the program. Can be a near (within same segment) or far (possibly in another segment). Far labels only exist as theory in this version of WASM. Near and far labels always mark a location in the code (not data). Labels are assumed to be near unless otherwise defined, including labels that are alone on a line. V. A string of any sequence of characters surrounded by single quotes. Note: semicolons and single quotes cannot be represented as a character in a string or as an immediate data character. These two characters can only be represented as numerical values. Operand types may be explicitly set by using the NEAR, FAR, and OFFSET special operands (see the Special Operands section). The following are examples of all the major operand types. Operands: Types 13 Immediate data: MOV AL,'W' ;move the ASCII value ;of upper-case w to AL ;the following lines all assemble to "move zero to AX" MOV AX,0 MOV AX,-21 + 21 MOV AX,-21 - -21 MOV AX,50000 * 0 MOV AX,-6 / -3 - 2 MOV AX,NOT 1111111111111111B MOV AX,0FFH-128-64-32-16-8-4-2-1 ;remember that numbers MUST start with 0 to 9, even ;hexadecimal numbers MOV AX,0FFFFH ;move ffff hex to AX Registers: ;8 bit examples MOV AL,DL MOV CL,0 ;16 bit examples MOV AX,DX MOV CX,0 ;segment examples MOV DX,SS MOV CX,0 MOV ES,CX ;cannot move immed. directly to seg Memory operands: ;direct reference examples MOV [100],AX PUSH DATA MOV DATA,0 ;the next three produce the same effect MOV CX,[DATA] ;OFFSET implied MOV CX,[OFFSET DATA] MOV CX,DATA ;this is best ;indirect reference examples MOV [BX],AX MOV DX,[BX+SI+100] INC BYTE [OFFSET DATA+DI-1001011B+BP-3] DATA DW ? Operands: Types 14 Near labels: LABEL1 LABLE2 LABEL NEAR LABEL3 NOP ;all three of these jump to the NOP instruction JMPS LABEL1 JMPS LABEL2 JMPS LABEL3 Strings: DB 'this is a string' ;this represents the string "semicolon ; semicolon" DB 'semicolon ',59,' semicolon' Operands: Sizes 15 If the value of one operand is directly acting upon the value of another operand (like adding or moving one to the other), the sizes of the operands must always agree. The size that is common between two operands must be an allowable size for the particular version of the instruction. Most operands are either 8 bits (byte) or 16 bits (word). The size of registers are always implicit. Registers come in 8 and 16 bit sizes. The size of memory operands are either implicit by the other operand, or must be explicitly set by the user. If the other (non-memory) operand is a register, the memory operand is assumed to be the same size as the register. If the other operand is immediate data, the size of the memory operand must always be defined by the user (this is because the size of immediate data may be ambiguous). The size of immediate data depends on its value and whether or not the operand is signed. Signed numbers in the range -128 to 127 are either 8 or 16 bit sizes. Signed numbers in the range -32768 to 32767 (but not -128 to 127) are only 16 bit size. Unsigned numbers are either 8 or 16 bit sizes if they are in the range 0 to 255, and just 16 bit size if they are 0 to 65535 (but not 0 to 255). These sizes are according to the actual number of bits it takes to represent the data. Operand sizes may be defined by the user through the BYTE, WORD, DWORD, QWORD, TBYTE and ANYSIZE special operands (see the Special Operands section). The DB, DW, and LABEL pseudo-ops automatically define the size of their labels for use as memory operands. Examples: Operands acting upon each other, sizes must agree: MOV AX,BX ;AX is 16 bit, BX is 16 bit ADD DX,0 ;DX is 16 bit, 0 can be 8 or ;16 bit MOV AL,128 ;AL is 8 bit, 128 is ;unsigned 8 or 16 bit MOV AL,+128 ;error!, AL is 8 bit, +128 is ;signed 16 bit Operands: Sizes 16 Operands not acting upon each other, sizes do not have to agree: IN AL,DX ;AL is 8 bit ;DX is 16 bit Memory operand assumed to be size of register: SUB BL,[BX+SI+10] ;8 bit subtract MUL AX,DATA ;16 bit multiply DATA DW 10 Memory operand size must be defined by user: STORAGE DW 0 ;STORAGE is 16 bit NUMBER EQU 100H ADD WORD [SI],NUMBER ;16 bit addition SUB STORAGE,1 ;16 bit subtraction, ;storage has been defined ;above in declaration MOV DATA, 254 ;8 bit move, DATA ;is defined below DATA LABEL BYTE ;DATA is 8 bit Operands: Values 17 All operands have a value, but unless the operand is some kind of immediate data the value is transparent to the user. Immediate data is stored as a 16 bit value. Signed numbers are stored in two's complement format. Operand values may be modified by using the NOT special operand (see the Special Operands section). Special Operands 18 Special operands act as function by taking a normal operand as an argument and returning, with possible modification, the type, size, and/or value of its argument. Special operands and an argument can usually be used in place of any normal operand. The format is: Special_Operand Argument At least one delimiter must separate the two. The argument for a special operand may not be extended. Special operands can never be signed, but their arguments can. Special operands should not be nested. The following are descriptions of all the special operands: NOT Returns the logical not (flip all bits) of its argument. Type and size are not changed. Accepts only immediate data as its argument. ;these two statements produce the same code MOV AL,NOT 1 MOV AL,FEH OFFSET Returns the offset of a label and makes the type immediate data and the size 16 bit. Accepts near, far, and memory labels as arguments. Used mainly to load the address of program data. ;put message location in SI MOV SI, OFFSET MESSAGE ;put message length in CX MOV CX, OFFSET END - OFFSET MESSAGE MESSAGE LABEL BYTE DB 'This is the message' END LABEL BYTE PROGRAM_SIZE This is not a normal special operand, in the sense that it does not have an argument. It returns the size of the program in bytes as a 16 bit immediate data operand. The information returned is exactly like the information returned by specifying the OFFSET of a label which has been declared at the end of the program minus 100H. Used mainly in defining a BLOAD program header. MOV AX,PROGRAM_SIZE ;size of program into AX Special Operands 19 NEAR Returns the value and size of its argument but changes the type to a near label. Accepts near labels, far labels, memory labels, and immediate data as arguments. Used mainly for the PROC pseudo-op. SUBROUTINE PROC NEAR NOP ENDP ;can be used for jumps to a literal address JMP NEAR 100 ;jump to beginning of prog. HERE JMPS NEAR 10 + OFFSET HERE ;jump 10 bytes forward FAR Is the same as NEAR except changes the type to a far label. Not used except for the PROC pseudo- op. BYTE Returns the value and type of its argument but changes the size to 8 bit. Accepts memory operands and immediate data as arguments. Used mainly for defining the size of a memory operand when the size of the operation would be ambiguous otherwise. MOV BYTE [BX], 0 ;8 bit move WORD Same as BYTE but sets size to 16 bit. DWORD Same as BYTE but sets size to 32 bit. Does not allow immediate data as an argument. Used mainly to specify an indirect intersegment call/jump instruction. CALL DWORD [BX] ;intersegment (far) jump QWORD Same as DWORD but sets size to 64 bit. Used for long real and long integer 8087 operands. Note: At the present time 8087 operands are not officially implemented by WASM. Special Operands 20 TBYTE Same as DWORD but sets size to 80 bit. Used for temporary real and BCD 8087 operands. Note: At the present time 8087 operands are not officially implemented by WASM. ANYSIZE Same as BYTE but sets size to all allowable sizes. Used mainly to declare a memory location that is being used for more than one size. DATA LABEL ANYSIZE ;data can be any size DS 2 ;this is the area marked by DATA ;both of these assignments will work correctly MOV AL,DATA ;8 bit move MOV AX,DATA ;16 bit move Combining Operands 21 Operands may consist of one or more expressions added (+), subtracted (-), multiplied (*), or divided (/) together to form an extended operand. Only near labels, far labels, memory labels, and immediate data can have additional expressions combined to them. All expressions after the first can only be immediate data. Any number of spaces may be between the expressions and their corresponding operators (the + ,-, *, or /). No commas may be used within a sequence of expressions (commas cause the final evaluation of an operand, thus terminating an extended operand). All extended operands are evaluated sequentially from left to right (parenthesis are not allowed). Special operands may be used within extended operands. Arguments for special operands themselves cannot be extended, i.e. the statement MOV AX,NOT 1+1 is interpreted as MOV AX,(NOT 1) + 1. If any expression of an extended operand is signed, the operand as a whole is considered signed. It's a good idea to make the first expression of an extended operand signed if the operand as a whole should be considered signed. Examples: MOV AX,1+1 ;move 2 into AX MOV SI,-6 + +3 / -1 * 2 + -6 ;move 0 into SI ADD BYTE DATA+1, 3 ;adds three to high ;byte of DATA DATA DW 0 Pseudo-Op Descriptions 22 Pseudo-op stands for pseudo operation. Pseudo-ops are not generally instructions for the processor, but commands for the assembler. The following are descriptions of all supported pseudo-ops: DB Declare bytes. Includes the list of operands in in the object code. There may be any number of operands (as long as they fit on one line). The operands may be any combination of strings and 8 bit immediate data. A label that marks a DB is considered a memory label and the data may be accessed through the label. The size of the label is defined to be 8 bit. MOV AL,DATA1 ;move the value at DATA1 (48) to AL MOV AL,DATA2 ;move the value at DATA2 (0) to AL DATA1 DB '0' DATA2 DB 0 DB 'Data may',' ','be',32 DB 'strings',1fH+1,'and',100000B,'numbers.' DS Declare storage. Includes the specified number of identically initialized bytes in the object code. There is one or two operands. The first is the number of bytes to declare, it is required. The second operand is optional. It specifies what value the bytes should be initialized to. If this operand is not included the bytes are initialized to zero. A label that marks a DS is considered a memory label and the data may be accessed through the label. The size of the label is left undefined. DS 10H ;declaring 16 bytes of 0 DS 10H,0FFH ;declaring 16 bytes of FFH Pseudo-Op Descriptions 23 DW Declare word. Includes the list of operands as 16 bit values in the object code. There may be any number of immediate data operands (as long as they fit on one line). A label that marks a DW is considered a memory label and the data may be accessed through the label. The size of the label is defined to be 16 bit. ;this construction can be useful ;for tables of routines DW OFFSET ROUTINE_ONE DW OFFSET ROUTINE_TWO DW OFFSET ROUTINE_THREE ;or alternately DW OFFSET ROUTINE_ONE,OFFSET ROUTINE_TWO, ... MOV AX,ONE ;move value at ONE to AX ;these two lines produce the same effect ONE DW 1 ;0001 DB 1,0 ;low byte stored first, 0001 ENDP End procedure. Specifies the end of a procedure. It has no operands. See PROC. EQU Equate symbol. Assigns immediate data or a direct address to a symbol, such that the symbol may be used instead. There is one operand, either immediate data or a number enclosed by brackets (direct address). A label for an EQU is always required. Equates need not be defined before they are used, unless they are used as operands for other equates. It is standard practice, though not necessary, to declare all equates at the start of the program SYMBOL1 EQU 1 MEM_SIZE EQU WORD [2] MOV AX,SYMBOL1 ;move 1 to AX MOV BYTE [SI+SYMBOL1],SYMBOL1 ;move 1 to [SI+1] MOV DX,MEM_SIZE ;move memory size ;from PSP to DX Pseudo-Op Descriptions 24 ERRORMAX Define maximum allowed errors. Sets the maximum allowed errors before halting the assembly and displaying "Too many errors." The single operand is a 16 (or 8) bit immediate data operand, the number of errors to allow. This instruction is useful for those of you who are particularly sensitive to errors. The default setting is 65535. ERRORMAX 0 ;for someone who simply cannot ;stand the sight of errors, ;actually halts assembly after the ;first error, is same as ERRORMAX 1 INCLUDE Include source code. Inserts the indicated source file immediately after the include. The single operand is a string containing the name of the file to be included. The extension and drive of the source file are used if none are specified. The entire file is inserted. Included files cannot have any INCLUDE's themselves. See the Assembly Listing section on how INCLUDE's affect the list output. Includes are useful for inserting source code that is used by many different programs. They are also useful for breaking up large programs and then including all the pieces together at assembly. ;include file EXTRA using source drive and extension INCLUDE 'EXTRA' ;include file EXTRA.INC using the source drive INCLUDE 'EXTRA.INC' Pseudo-Op Descriptions 25 LABEL Label definition. Allows the definition of a particular type of label. The single operand is one of the following: NEAR, FAR, BYTE, WORD, DWORD, QWORD, TBYTE, or ANYSIZE. The label of the LABEL instruction becomes a near or far label if either of those operands are used. If a size operand is used, the label becomes a memory label of the indicated size. The location assigned to the label is the present value of the location counter (just as if the label was marking a line of code or data). LABEL, of course, always requires a label. LABEL is useful for creating a memory label of a specific size that marks the beginning of a data area. ;storage area of 5 words WORDS LABEL WORD DS 10 ;MEM_SIZE marks the memory size word in the PSP ORG 2 MEM_SIZE LABEL WORD ;these two near labels mark a location in the code JUMPLOC1 ;WASM interprets this as the thing below JUMPLOC2 LABEL NEAR ;this is more technically correct LINESIZE Line size setting. Sets the listing width. Has one or more 8 bit immediate data operands. The first operand is the actual width, the following operands are printer set-up codes. The printer set-up codes are sent directly to the printer if (and only if) the list file was specified as PRN. The width includes the entire list line (location counter, object code, etc.). If a list line is greater then the width, it is truncated appropriately. The minimum width is 50 and the maximum width is 254. The default width setting is 79. LINESIZE is useful for generating a listing of source code with extra long lines. LINESIZE 79 ;default ;compressed width of IBM matrix printer, 15 is the ;control code to make printer print in compressed ;mode LINESIZE 132,15 Pseudo-Op Descriptions 26 LIST+, LIST- List on, list off. LIST+ turns the listing on and LIST- turns the listing off. There are no operands for either pseudo-op. If no file has been specified for list output and a LIST+ is encountered, the listing will be activated and sent to the screen. The list pseudo-ops are useful when only a partial listing of a program is desired. ORG Origin. Allows modification of the location counter by the source code. It has one 16 (or 8) bit immediate data operand. The default starting location is 100H, which is the offset that COM files are loaded. Origin is used mainly for programs that aren't meant to be COM files. Also used for defining labels via the LABEL pseudo-op. ORG 0 ;this begins a BASIC subroutine PAGE+/PAGE- Page on, page off. PAGE+ turns the automatic paging of the list output on and PAGE- turns the paging off. PAGE+ has an optional 16 (or 8) bit immediate data operand and an optional string operand. If the immediate data operand is included it becomes the page number, otherwise the page is incremented from the last page number. If the string operand is included it becomes the new subtitle at the top of the page, starting with the present page. The immediate data operand must come before the string operand if both are included. PAGE+ always starts a new page. PAGE+ ;start paging using last page number PAGE+ 1 ;start paging with page one PAGE- ;stop paging PAGE+ 1,'Initialization Routine' ;start paging with page 1 using the ;subtitle "Initialization Routine" Pseudo-Op Descriptions 27 PAGE New page. Starts a new page. Has an optional 16 (or 8) bit immediate data operand and an optional string operand. If the immediate data operand is included it becomes the page number, otherwise the page is incremented from the last page number. If the string operand is included it becomes the new subtitle at the top of the page, starting with the present page. The immediate data operand must come before the string operand if both are included. PAGE ;start a new page, incrementing ;from last page number PAGE 1 ;start a new page with page one PAGE 'Data' ;start new page with ;"Data" as the subtitle, this ;is probably the best way to ;start a new section of the ;program PAGE 1,'Data' ;start a new page with page ;one and "Data" as the ;subtitle PAGESIZE Define page size. Sets the number of lines per page. Has one 8 bit immediate data operand. The lines per page include the lines of the title, subtitle, list heading, etc. The minimum page size is 15 and the maximum page size is 255. The default page size is 60. PAGESIZE 255 ;this makes very long pages Pseudo-Op Descriptions 28 PROC Procedure begin. Specifies the beginning of a procedure. It has one operand which is either NEAR or FAR. The operand determines the type of returns that will be used for the RET's within the procedure and the type of the label (if any) that marks the PROC statement. NEAR means within segment and FAR means intersegment. The main program is usually a FAR procedure, while the subroutines within it are usually NEAR procedures. ENDP is used to terminate a procedure. Procedures may be nested 10 deep. PROC FAR : <main body of program> : SUBROUT PROC NEAR : <subroutine> : ENDP ;end of subroutine ENDP ;end of main program SUBTITLE Subtitle setting. Sets the subtitle for the start of each following page. The single string operand becomes the new subtitle. Note that SUBTITLE sets the subtitle for the following page, not the page that the SUBTITLE statement appears; because of this reason setting the subtitle may be better serviced by the other pseudo-ops that can do the same thing (TITLE, PAGE, and PAGE+). The SUBTITLE pseudo-op is optional. If not included in the program the subtitle will be blank. SUBTITLE 'Chapter 1' ;subtitle for all ;following pages becomes ;"Chapter 1" TITLE Title setting. Sets the title for the start of each page. Has one or two string operands. The first is required and becomes the title. The second is optional and becomes subtitle for the initial starting page. Though the SUBTITLE, PAGE, and PAGE+ pseudo-ops can all set the subtitle, none of them can set the subtitle of the initial starting page. The TITLE pseudo-op is optional. If not included in the program the title will be blank. Only one title statement works, i.e. the entire program uses the same title. TITLE 'Super Program','Starting Subtitle' WASM Instruction Set 29 This section is not intended to fully describe the function of the 8088 instructions, but only list the way WASM implements each one. For a comprehensive description of the 8088 instructions get a book on the subject. The pseudo operations are fully described under in the Pseudo-Op Descriptions section. See also the Source Code Clarification section for possible enlightenment on the differences between WASM and other assembler conventions. Instruction Format: <mnemonic> = <short description> <operand> [,<operand>] [=<comment>] Operand Types: none no operands reg register (non-segment) seg segment register acum AX or AL mem memory operand immed immediate data string string data Operands separated by slashes mean that either type may be used. Operands in capital letters are the literal operands accepted. Operands in brackets are optional, all others are required. Numbers in parenthesis indicate the allowable size (number of bits) for the specified operands. If no size is given then the operands may be either 8 or 16 bit (where applicable). Pseudo-Ops DB = declare bytes immed(8)/string [, immed(8)/string, ...] DS = declare storage immed [, immed(8)] = second operand assumed 0 DW = declare words immed [, immed, ...] ENDP = end of procedure none EQU = equate, requires label immed/mem = mem can only be a direct address ERRORMAX = set maximum errors, default 65335 immed WASM Instruction Set 30 INCLUDE = include source file string = file name, default to source drive and ext LABEL = define label, requires label NEAR/FAR/BYTE/WORD/DWORD/QWORD/TBYTE/ANYSIZE LINESIZE = set output width, default 79 immed(8) [, immed(8), ...] = width and printer codes LIST+ = list output on none LIST- = list output off none ORG = origin, default 100H immed PAGE = start new page [immed/string] = page number, subtitle immed [, string] = page number, subtitle PAGE+ = start auto paging [immed/string] = page number, subtitle immed [, string] = page number, subtitle PAGE- = stop auto paging, default setting none PAGESIZE = set lines per page, default 60 immed PROC = beginning of procedure NEAR/FAR SUBTITLE = set program subtitle, default none string = subtitle TITLE = set program title, default none string [, string] = title, subtitle Data Transfer IN = input acum, immed(8) = input from a fixed port acum, DX = input from a variable port in DX LAHF = load AH with flags none LDS = load DS and register (16) reg, reg/mem LEA = load effective address (16) reg, reg/mem WASM Instruction Set 31 LES = load ES and register (16) reg, reg/mem MOV = move reg/mem, reg/seg reg/seg, reg/mem reg/mem, immed OUT = output immed(8), acum = output to fixed port DX, acum = output to variable port in DX POP = pop (16) reg/seg/mem POPF = pop flags none PUSH = push (16) reg/seg/mem PUSHF = pop flags none SAHF = store AH to flags none XCHG = exchange reg/mem, reg reg, reg/mem XLAT = translate byte in AL none Arithmetic AAA = ASCII adjust for add none AAD = ASCII adjust for divide none AAM = ASCII adjust for multiply none AAS = ASCII adjust for subtract none ADC = add with carry reg/mem, reg reg, reg/mem reg/mem, immed ADD = add reg/mem, reg reg, reg/mem reg/mem, immed WASM Instruction Set 32 CBW = convert byte to word none CWD = convert word to double word none DAA = decimal adjust for add none DAS = decimal adjust for subtract none DEC = decrement reg/mem DIV = divide, unsigned [acum,] reg/mem = acum implicit IDIV = integer divide, signed [acum,] reg/mem = acum implicit IMUL = integer multiply, signed [acum,] reg/mem = acum implicit INC = increment reg/mem MUL = multiply, unsigned [acum,] reg/mem = acum implicit NEG = decrement reg/mem SBB = subtract with borrow reg/mem, reg reg, reg/mem reg/mem, immed SUB = subtract reg/mem, reg reg, reg/mem, reg/mem, immed Logic AND = and reg/mem, reg reg, reg/mem reg/mem, immed NOT = not reg/mem WASM Instruction Set 33 OR = or reg/mem, reg reg, reg/mem reg/mem, immed RCL = rotate through carry left reg/mem = one time reg/mem, CL = CL times RCR = rotate through carry right reg/mem = one time reg/mem, CL = CL times ROL = rotate left reg/mem = one time reg/mem, CL = CL times ROR = rotate right reg/mem = one time reg/mem, CL = CL times SAL = shift arithmetic left reg/mem = one time reg/mem, CL = CL times SAR = shift arithmetic right reg/mem = one time reg/mem, CL = CL times SHL = shift logical left reg/mem = one time reg/mem, CL = CL times SHR = shift logical right reg/mem = one time reg/mem, CL = CL times XOR = xor reg/mem, reg reg, reg/mem reg/mem, immed Flag Setting CLC = clear carry none CLD = clear direction none CLI = clear interrupt none CMC = clear complement carry none WASM Instruction Set 34 CMP = compare reg/mem, reg reg, reg/mem reg/mem, immed STC = set carry none STD = set direction none STI = set interrupt none TEST = test reg/mem, reg reg, reg/mem reg/mem, immed Control Transfer CALL = call near = direct within segment immed (offset), immed (segment) = direct intersegment reg/mem = indirect within segment (16) mem = indirect intersegment (32) INT = interrupt immed(8) INT3 = type 3 interrupt none INTO = interrupt on overflow none IRET =interrupt return none JA = jump if above near JAE = jump if above or equal near JB = jump if below near JBE = jump if below or equal near JC = jump if carry near JCXZ = jump if CX equal to zero near WASM Instruction Set 35 JE = jump if equal near JG = jump if greater near JGE = jump if greater or equal near JL = jump if less near JLE = jump if less or equal near JMP = unconditional jump near = direct within segment immed (offset), immed (segment) = direct intersegment reg/mem = indirect within segment (16) mem = indirect intersegment (32) JMPS = unconditional short jump near JNA = jump if not above near JNAE = jump if not above or equal near JNB = jump if not below near JNBE = jump if not below or equal near JNC = jump if no carry near JNE = jump if not equal near JNG = jump if not greater near JNGE = jump if not greater or equal near JNL = jump if not less near JNLE = jump if not less or equal near JNO = jump if not overflow near WASM Instruction Set 36 JNP = jump if not parity near JNS = jump if not sign near JNZ = jump if not zero near JO = jump if overflow near JP = jump if parity near JPE = jump if parity even near JPO = jump if parity odd near JS = jump if sign near JZ = jump if zero near LOOP = loop CX times near LOOPE = loop while equal near LOOPNE = loop while not equal near LOOPNZ = loop while not zero near LOOPZ = loop while zero near RET = return, type determined by procedure none immed = add immed to stack RETF = within segment return none immed = add immed to stack RETN = intersegment return none immed = add immed to stack WASM Instruction Set 37 String Manipulation CMPSB = compare string byte none CMPSW = compare string word none LODSB = load string byte none LODSW = load string word none MOVSB = move string byte none MOVSW = move string word none REP = repeat CX times none REPE = repeat while equal none REPNE = repeat while not equal none REPNZ = repeat while not zero none REPZ = repeat while zero none SCASB = scan string byte none SCASW = scan string word none STOSB = store string byte none STOSW = store string word none Processor Control HLT = halt none LOCK = bus lock prefix none WASM Instruction Set 38 NOP = no operation none SEG = segment override prefix seg WAIT = wait none Source Code Clarification 39 Many of the conventions used by WASM are used by other assemblers and debuggers. This section compares WASM to other assemblers and the DEBUG program provided with DOS. This section also points out a few particulars of WASM syntax. Some assemblers add a suffix to the mnemonic to indicate the size of the operation, whether immediate data is involved, and the type of calls, jumps, and returns that are being used. WASM identifies the type and size of the instruction mainly on the basis of the operands, in accordance with the DOS DEBUG program. WASM allows the user define the size of the operand through the use of a special operand (BYTE, WORD, etc.), this is very similar to the structure used by the DEBUG program and the IBM Macro Assembler. ; the following statement in WASM... MOV WORD [5+SI+ 10 +BP+5], NOT 1111111111111111B ; ...is disassembled as the following in DEBUG ; MOV W,[BP+SI+14],0000 ;DOS 1.1 DEBUG ; MOV WORD PTR [BP+SI+14],0000 ;DOS 2.0 DEBUG The size of the string manipulation instructions are specified by a B or W suffix added to the mnemonic. This is the same as the DEBUG program. MOVSB ;move string byte MOVSW ;move string word JMPS is the mnemonic that WASM uses to specify a short unconditional jump to a near label. JMP always means a long jump. The (DOS 2.0) DEBUG program uses JMP for both long and short jumps. Indirect calls and jumps are specified by the DEBUG program as either near (within segment) or far (intersegment). WASM makes the distinction by the size of the operands, i.e. a 16 bit operand is near, and a 32 bit operand is far. CALL OFF,SEG ;direct call to OFF ;offset and SEG segment JMPS LOCATION1 ;short unconditional jump JMP LOCATION1 ;long unconditional jump JMP WORD [SI+BX] ;indirect jump in same segment CALL DWORD [BX] ;indirect intersegment call Source Code Clarification 40 WASM sets the type of return for a RET based on the last PROC (see the PROC pseudo-op in the Pseudo-Op Descriptions section). A near (within segment) or far (intersegment) return may be encoded without using a PROC through the use of RETN and RETF respectively. The DEBUG program uses RET to indicate a near return and a RETF to indicate a far return. PROC FAR ;<--- RET ;far return ; far routine RETN ;near return ; RETF ;far return ; ; PROC NEAR ; <--- RET ;near return ; ; near routine RETN ;near return ; ; RETF ;far return ; ; ENDP ; <--- ; RET ;far return ; ENDP ;<--- The bit shifting instructions (SHL, SHR, ROL, etc.) are interpreted to be a single shift by WASM if there is only one operand (the operand to be shifted). Shifts using the CL register to count the shift are implemented by specifying CL as a second operand. The DEBUG program requires a "1" as a second operand to specify a single shift. ROL AX ;roll AX left by one ; ROL AX,1 ;roll AX left by one, DEBUG format SHR BYTE [BX],CL ;shift 8 bits at [BX] CL times Some assemblers leave out an operand if the operand is implicit in the instruction. AX is implicit in the following instructions: IN, OUT, MUL, IMUL, DIV, and IDIV. WASM requires the AX (or AL) register in the IN and OUT instructions but allows the others with or without it. The DEBUG program leaves out the AX or AL register on multiply or divide instructions, but does not on the others. IN AX,DX ;AX recieves input word from port in DX ;both of the following are: AX = AX x CX MUL AX,CX ;WASM allows this MUL CX ;WASM and DEBUG allow this Source Code Clarification 41 WASM and DEBUG implement instruction prefixes as a separate instruction, i.e. they appear on the line above the instruction to modify. The prefixes are: LOCK, REP, REPE, REPNE, REPNZ, REPZ, and SEG. REP STOSB ;store byte CX times SEG SS MOV AX,[BX] ;[BX] is in the stack segment WASM and DEBUG both specify indirect memory operands by putting all values and registers inside the brackets. ;this in WASM ... SUB [BX+10],AX SUB [BX+DATA],AX ;... may be implemented by others like one of these ; SUB [BX]+10,AX ; SUB 10[BX],AX ; SUB DATA[BX],AX DATA LABEL WORD The mnemonic for an optimized type 3 interrupt is INT3. ;both of statements these cause type 3 interrupts, ;but the first uses only one byte of code INT3 INT 3 WASM assumes the entire program and all data are in the same segment, so there are no segment definitions. The location counter is automatically started at 100H, in accordance with COM file format. Note that several WASM instructions mean the same thing as other instructions and produce identical object code. The DEBUG program always disassembles these instructions using one particular mnemonic. One example is JNLE (jump not less or equal) and JG (jump greater). The DEBUG program disassembles both of these instructions as JG. Source Code Clarification 42 There is an uncaught error for certain registers as operands. When the operand DX is used in IN's and OUT's, and CL is used for shifts and rolls, WASM only looks for a register type, not those particular registers. This means that in those cases any register will work in place of a DX or CL (except a segment register). Also WASM does not search for extra operands, they do not cause errors if they are there. ;some uncaught errors IN AX,BX SHL AX,BX MOV AX,BX,CX,DX Errors: Message Format 43 Errors detected in the source code cause the output of an error message and then the line that caused the error. A line may have more than one error message. Note that paging occurs indiscriminately so that the error(s) for a line may be on a different page then the line itself. Error messages and the line being flagged are output even if there is no listing otherwise being generated. If an error causes the premature termination of the assembly, WASM prints the error message on the screen along with ">>>Cannot Continue<<<" and a beep. Diagnostics are output in a similar manner to errors. Diagnostics are provided as helpful advice and do not in themselves constitute an error. Errors: Messages 44 A file cannot be included by an included file Source code that was included into the main program by an INCLUDE contained an INCLUDE. Included files cannot have any INCLUDE's. Address error There was some kind of error in the addressing operands, probably an illegal combination of registers such as [BX+BP]. Ambiguous memory reference The size of an operand was found to be undefined when it shouldn't be. Usually occurs when the operands are a memory operand and immediate data, and the size of the prior is not defined. Also occurs if the operand for a LABEL statement is missing. Cannot create list file: <file name> WASM was unable to create or open the specified list file. Could be an error in the file name. The file name is displayed. Critical error. Cannot create object file: <file name> WASM was unable to create or open the specified object file. Could be an error in the file name. The file name is displayed. Critical error. Could use JMPS: <offset> A diagnostic offered when the displacement of the jump was found to be small enough to use the short unconditional jump (JMPS). The hexadecimal number displayed is the offset. Though the present code is not incorrect, changing the instruction to a JMPS would save a byte of object code. Data too long in declaration: <value> Data too long in declaration: <operand> The first version is caused by the second operand in a DS being more than a byte long. WASM displays the hexadecimal value of the operand. The second version is caused when an operand in a DB is more then a byte long. The operand itself is displayed. Disk full or write error: <file name> For some reason WASM could not successfully write to the list or object file. The file name is displayed. Usually means that the disk is full. Critical error. Division by zero: <expression> The divisor of a division operation within an extended operand was found to be zero. The division is ignored and the expression which is equal to zero is displayed. Errors: Messages 45 Duplicate definition: <symbol> A symbol was defined more than once. Each definition is flagged. One of the occurrences must be differentiated from the other to fix the error. All symbols must be unique from each other. ENDP without PROC An ENDP was found without a PROC to match it. EQU without label The line contains an EQU but doesn't have a label. An EQU is meaningless without a label, thus labels are always required. Illegal addressing operand: <operand> The displayed operand was used in addressing (found between brackets) but is not a legal addressing operand. Illegal argument for ANYSIZE: <operand> The displayed operand was given as an argument for ANYSIZE but is not immediate data or a memory operand. Illegal argument for BYTE: <operand> The displayed operand was given as an argument for BYTE but is not immediate data or a memory operand. Illegal argument for DWORD: <operand> The displayed operand was given as an argument for DWORD but is not a memory operand. Illegal argument for FAR: <operand> The displayed operand was given as an argument for FAR but is not a near label, far label, memory label, or immediate data. Illegal argument for NEAR: <operand> The displayed operand was given as an argument for NEAR but is not a near label, far label, memory label, or immediate data. Illegal argument for NOT: <operand> The displayed operand was given as an argument for NOT but is not immediate data. Illegal argument for OFFSET: <operand> The displayed operand was given as an argument for OFFSET but is not a near, far, or memory label. Illegal argument for QWORD: <operand> The displayed operand was given as an argument for QWORD but is not a memory operand. Note: At the present time 8087 operands are not officially implemented by WASM. Errors: Messages 46 Illegal argument for ST: <operand> The stack offset (the i in ST(i)) of an 8087 stack operand was not immediate data in the range 0 to 7. Note: At the present time 8087 operands are not officially implemented by WASM. Illegal argument for TBYTE: <operand> The displayed operand was given as an argument for TBYTE but is not a memory operand. Note: At the present time 8087 operands are not officially implemented by WASM. Illegal argument for WORD: <operand> The displayed operand was given as an argument for WORD but is not immediate data or a memory operand. Illegal number or symbol: <operand>: <character> The displayed operand begins begins with a 0 through 9 but is not a legal number (contains a non-numeric character). Following the operand is the specific character causing the error. Symbols cannot start with a 0 through 9, and any operand that does is assumed to be a number. Make sure that hexadecimal numbers end with an H and have a preceding 0 (if the first character would otherwise be an A through F). Illegal operand in declaration: <operand> The displayed operand was used in a DB but is not immediate data or a string, or was used in a DW and is not immediate data. Illegal operand(s) WASM was unable to find a version of the instruction that used the same operands as those in the source code. Is probably because one or more of the operands are the wrong type or size, but also may be because there are too few operands for the instruction. Often be due to other errors in the statement. Errors: Messages 47 Illegal operator or symbol: <character> The displayed character was in the position of a sign or operator but is illegal for some reason. May be because of multiple operators (signs) for a single operand like MOV AL,--1. May be because there is a sign for a special operand (special operands may not be signed, though arguments can be). May be because of an inappropriate bracket like MOV ] AX,0. Also occurs if the operator within an address operand is illegal or missing like MOV AX,[BX SI] or MOV AX,[BX-SI]. Symbols may not contain any operators, brackets or other special characters. These types of illegal characters in a symbol results in an uncaught error when the symbol is defined. If such a symbol is used as an operand it will probably be parsed into separate pieces, possibly causing this error in the process. Illegal or undefined pseudo operation This error should never occur, if it does there is something wrong with WASM (namely that a pseudo-op has been included in the instruction set without informing WASM about it). Illegal printer code: <operand> The displayed operand was specified as a printer code (an extra width operand) but is not 8 bit immediate data. Illegal reference Occurs when the pass one value of an operand might be different than the pass two value in situations where it shouldn't be. Specifically occurs if the OFFSET special operand is used for a DS, EQU, or an ORG. Also occurs if the operand for an EQU is undefined at the time the EQU is defined. INCLUDE file not found: <file name> The file specified by the INCLUDE could not be found or could not be opened. Could be an error in the file name. The file name is displayed. INCLUDE pseudo-op disabled This error should never occur, if it does there is something wrong with WASM. Occurs if INCLUDE has been disabled and then one is encountered. INCLUDE's cannot normally be disabled by the user. Invalid character in symbol: <symbol> The displayed symbol begins with a 0 through 9, which is reserved for numbers. Symbols should begin with a letter. Errors: Messages 48 Invalid operand size A diagnostic that is sometimes offered when an Illegal Operands error occurs. It means that WASM found a version of the instruction that matched the source code in every way except in the size of one or more of the operands. Adjusting the size might result in correct code. LABEL without label The line contains a LABEL but doesn't have a label. LABEL is meaningless without a label, so labels are always required. LINESIZE out of range: <value> The operand for LINESIZE was too big or too small. LINESIZE must be in the range 50 to 254. The decimal value of the operand is displayed. Missing ENDP: <number> The end of the source code was encountered but there were more PROC's than ENDP's. The decimal number displayed is the number of missing ENDP's. Missing PROC A RET not inside a procedure (PROC...ENDP structure) was found. The RET instruction needs a PROC to set the type of return. Missing right bracket An operand began with a left bracket, indicating a memory operand, but no matching right bracket was found before the end of the line was reached. Operand cannot be combined: <expression> The first expression of an extended operand was not a near label, far label, memory label, or immediate data. Or the expression after the first was not immediate data. The expression causing the error is displayed. Operands are incompatible sizes The sizes of the operands were found to be incompatible, like adding a 16 bit value to an 8 bit location. Out of memory for symbol table: <symbol>: <number> The symbol table is full. The symbol that would not fit is displayed. Also displayed is the decimal number of symbols presently in the table. This error can only be fixed by reducing the number or length of the symbols in the program, or by increasing the amount of available memory. Critical error. Errors: Messages 49 Overflow: <operand> A specific operand or an extended operand resulted in a value that was too big (or too small) to be represented by 16 bits. The specific operand or expression causing the overflow is displayed. Unsigned values must be 0 to 65535, signed must be -32768 to +32767. Note that if an extended operand contains any signed expressions the entire operand is considered signed. PAGESIZE out of range: <value> The operand for PAGESIZE was too big or too small. The number of lines per page must be in the range 15 to 255. The decimal value displayed is the value of the operand. Phase error: <value> The value of a label was found to be different on pass one and pass two. Never caused by the line that gets flagged (error occurred sometime previously). Clearing up other errors almost always fixes a phase error. Phase errors can also result from statements like " ORG OFFSET label" or " DS OFFSET label" because the expression "OFFSET label" might return different values on different passes (screwing up the location counter). The hexadecimal value displayed is the pass one value of the label, the pass two value is displayed on line itself. The assembled code always uses the pass one value. If a phase error occurs without any other errors it is possible that it is being caused by some error within WASM. Procedures nested too deeply: <level> The procedures within the program were nested too deeply. Procedures can only be nested ten deep. The PROC causing the error is ignored. The decimal number displayed is the present nesting level, which should always be ten. Register overriding declared memory size A diagnostic to warn the user that a register is acting upon or being acted upon by a memory operand that has a different size. This message can be avoided by redefining the size of the memory operand through the use of BYTE, WORD, or ANYSIZE (whichever is appropriate). Should be byte data The immediate data (port) of an IN or OUT did not have an 8 bit size. Source file not found: <file name> The source file was not found or could not be opened. The name of the file is displayed. Could be an error in the file name. Critical error. Errors: Messages 50 String not closed A single quote to start a string was found, but WASM did not find a matching quote to close the string. Syntax error: <mnemonic> The displayed mnemonic was not recognized as a legal WASM instruction. Too far for short jump: <offset> The offset of the jump is too far for a short jump. If the instruction is a JMPS then JMP may be successfully substituted, otherwise the only way to correct this error is to somehow change the code so that the jump location is closer. The hexadecimal displacement is displayed, which can give an idea of how much closer the jump location must be. Short jumps must be in the range FF80 to 007F hexadecimal (-128 to 127 decimal). Too many errors: <number> The number of errors detected exceeded or equaled the maximum number of errors set by ERRORMAX (or the default number of 65535). The number of errors is displayed. Critical error. Undefined error This error should never happen. If it does there is something wrong with WASM. The error means that an error occurred for which there is no error message. Undefined symbol: <symbol> The displayed symbol was not a recognized operand type and not in the symbol table. Unexpected end of operand: <character> A special character (like +, /, *, etc) was found at the end of the line. Either get rid of the character or put something after it. WASM detects checksum failure The internal checksum failed. That particular copy of WASM.COM is no good (might have been garbled in transmission). Critical error. WASM detects insufficient memory There isn't enough available memory for WASM to run. Requires more memory. Critical error. Programming: Structure 51 When programming in assembler it is easy to give way to unstructured programming. There is no implicit structure to assembler (as there is with Pascal, for instance). For very short programs the structure is hardly significant, but the longer a program is the more important the structure becomes. A structured program is much easier to understand and DEBUG. To assist in structured programming, the source code is broken up into procedures with PROC's and ENDP's. PROC defines the beginning of a procedure, and ENDP defines the end. For every PROC there should be an ENDP. The whole program should be made a procedure containing smaller procedures within it. A reasonable way to order a program might be: equates, code, subroutines and data. A program might look something like this: PROC FAR ;beginning of main program : <equates> : : ;<-- : ; main program <code> ; : ; INT 20H ;<-- SUBRNT PROC NEAR ;<-- : ; SUBRNT subroutine <code> ; : ; : ; <data> ; : ; RET ; ENDP ;<-- : <data> : ENDP ;end of main program Programming: Operating System Interface 52 The DOS operating system creates and maintains the little world in which your program exists. DOS creates a free segment within memory and sets all the segment registers to its location. Then your program is loaded at offset 100H in that segment. The stack pointer is set to the top of the segment (you generally do not have to worry about the stack). Finally your program is given control and execution begins with the instruction at 100H. Those first 100H bytes that are just in front of your program are called the program segment prefix (PSP). The PSP contains many things that could be useful to your program, including any parameters entered when the program was executed. The DOS manual explains the PSP. Programming: Interrupts 53 To communicate with the rest of the world your program uses interrupts. Interrupts do things like printing characters to the screen, reading and writing to disk drives, and inputting what is being typed at the keyboard. There are interrupts provided by DOS and ROM BIOS. The DOS interrupts are explained in the back of the DOS manual and the BIOS interrupts are explained in the technical reference manual. Interrupts basically work by putting any required parameters into specified registers and calling the interrupt. An important interrupt that you should learn right away is interrupt 20H. This interrupt properly terminates a program and gives control back to DOS. All programs that are meant to run directly from DOS should end with: INT 20H ;exit to DOS Programming: BASIC Subroutines 54 Programs written in assembly language can be called from BASIC. See the BASIC manual for details. The user can easily make a machine language subroutine BLOADable by adding the proper header to the beginning of the program, which amounts to the following code at the start of the program: ORG 0 ;begin at offset 0 DB FDH ;BLOAD marker DW F000H ;segment to load it at DW 0 ;offset to load it at DW PROGRAM_SIZE ;size of program The segment and offset of the load location can be any number, since it should be specified by the user when loading it from BASIC, though making the address F000:0000 (which is read only memory) will prevent loading it over something important if the address is not specified. Since BLOADable files are not directly executable, their extension should be something other than COM (the default). Programming: Debugging your program Writing a program and assembling it is just the first step to creating a working program. To make that program function correctly usually requires some amount of debugging. This is done with DEBUG.COM, a utility program that is very conveniently provided with DOS. This program is just as important as the assembler itself. With DEBUG you can watch the execution of your program and see exactly what it is (or isn't) doing. DEBUG is fully explained in the DOS manual. A few of the most important commands are: (d)ump -- display memory, (e)nter -- change memory, (g)o -- execute code with breakpoints, (r)egister -- change and display register values, (t)race -- step through individual instructions, and (u)nassemble -- displays memory as assembler like instructions. Remember that an assembled program looks quite a bit different than one unassembled by DEBUG. Instead of branching to labels you are now branching to displacements (DEBUG translates the displacement into a memory location). Also many instructions produce identical code, like: JC xxxx ;jump if carry JB xxxx ;jump if below JG xxxx ;jump if greater JNLE xxxx ;jump if not less or equal XCHG AX,BX ;exchange AX and BX XCHG BX,AX ;exchange BX and AX When programming in assembler it is fairly easy to "crash" the system, mainly by executing non-code or falling into an infinite loop (you can't just break out of an infinite loop in assembler). It might be a good idea to NOT have any other tasks running concurrently when programming in assembler. Reserved Symbols 56 The following are guidelines for what not to use as symbols. All of these symbols have special meaning to WASM: AX AL ES BYTE CX CL CS WORD DX DL SS DWORD BX BL DS QWORD SP AH NOT TBYTE BP CH OFFSET ANYSIZE SI DH NEAR ST DI BH FAR PROGRAM_SIZE All fields beginning with 0 to 9 are reserved for numbers. The following characters should never be used in symbols: commas, spaces, any control characters, +, -, *, /, [, ], (, and ). It is recommended that all symbols start with a letter and consist of only letters, numbers and underscores. Technical Notes 57 The following are some theoretical upper limits to the source code: Symbol size .................. 255 Line size .................... 255 Total number of lines ........ 65535 Total number of symbols ...... 65535 Bytes of code ................ 65535 None of these values are checked and unexpected results may occur if any of them are exceeded. It is recommended that symbols and lines are kept to nice "reasonable" sizes, like no more than 100 or so characters. The symbol table is what really limits the size of the programs that can be assembled. If a full segment of memory (64K) is available to WASM version 1.0 (the most it can use), the symbol table has room for about 2080 ten byte symbols.